home *** CD-ROM | disk | FTP | other *** search
- /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
- /* ***** BEGIN LICENSE BLOCK *****
- * Version: MPL 1.1/GPL 2.0/LGPL 2.1
- *
- * The contents of this file are subject to the Mozilla Public License Version
- * 1.1 (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- * http://www.mozilla.org/MPL/
- *
- * Software distributed under the License is distributed on an "AS IS" basis,
- * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
- * for the specific language governing rights and limitations under the
- * License.
- *
- * The Original Code is mozilla.org code.
- *
- * The Initial Developer of the Original Code is
- * Netscape Communications Corporation.
- * Portions created by the Initial Developer are Copyright (C) 1998
- * the Initial Developer. All Rights Reserved.
- *
- * Contributor(s):
- *
- * Alternatively, the contents of this file may be used under the terms of
- * either the GNU General Public License Version 2 or later (the "GPL"), or
- * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
- * in which case the provisions of the GPL or the LGPL are applicable instead
- * of those above. If you wish to allow use of your version of this file only
- * under the terms of either the GPL or the LGPL, and not to allow others to
- * use your version of this file under the terms of the MPL, indicate your
- * decision by deleting the provisions above and replace them with the notice
- * and other provisions required by the GPL or the LGPL. If you do not delete
- * the provisions above, a recipient may use your version of this file under
- * the terms of any one of the MPL, the GPL or the LGPL.
- *
- * ***** END LICENSE BLOCK ***** */
-
- #include "nsISupports.idl"
-
- interface nsIDOMDocument;
- interface nsIDOMEventListener;
- interface nsIChannel;
- interface nsIVariant;
-
- /**
- * Mozilla's XMLHttpRequest is modelled after Microsoft's IXMLHttpRequest
- * object. The goal has been to make Mozilla's version match Microsoft's
- * version as closely as possible, but there are bound to be some differences.
- *
- * In general, Microsoft's documentation for IXMLHttpRequest can be used.
- * Mozilla's interface definitions provide some additional documentation. The
- * web page to look at is http://www.mozilla.org/xmlextras/
- *
- * Mozilla's XMLHttpRequest object can be created in JavaScript like this:
- * new XMLHttpRequest()
- * compare to Internet Explorer:
- * new ActiveXObject("Msxml2.XMLHTTP")
- *
- * From JavaScript, the methods and properties visible in the XMLHttpRequest
- * object are a combination of nsIXMLHttpRequest and nsIJSXMLHttpRequest;
- * there is no need to differentiate between those interfaces.
- *
- * From native code, the way to set up onload and onerror handlers is a bit
- * different. Here is a comment from Johnny Stenback <jst@netscape.com>:
- *
- * The mozilla implementation of nsIXMLHttpRequest implements the interface
- * nsIDOMEventTarget and that's how you're supported to add event listeners.
- * Try something like this:
- *
- * nsCOMPtr<nsIDOMEventTarget> target(do_QueryInterface(myxmlhttpreq));
- *
- * target->AddEventListener(NS_LITERAL_STRING("load"), mylistener,
- * PR_FALSE)
- *
- * where mylistener is your event listener object that implements the
- * interface nsIDOMEventListener.
- *
- * The 'onload' and 'onerror' attributes moved to nsIJSXMLHttRequest,
- * but if you're coding in C++ you should avoid using those.
- */
- [scriptable, uuid(7b3b3c62-9d53-4abc-bc89-c33ce78f439f)]
- interface nsIXMLHttpRequest : nsISupports
- {
- /**
- * The request uses a channel in order to perform the
- * request. This attribute represents the channel used
- * for the request. NULL if the channel has not yet been
- * created.
- *
- * In a multipart request case, this is the initial channel, not the
- * different parts in the multipart request.
- *
- * Mozilla only. Requires elevated privileges to access.
- */
- readonly attribute nsIChannel channel;
-
- /**
- * The response to the request is parsed as if it were a
- * text/xml stream. This attributes represents the response as
- * a DOM Document object. NULL if the request is unsuccessful or
- * has not yet been sent.
- */
- readonly attribute nsIDOMDocument responseXML;
-
- /**
- * The response to the request as text.
- * NULL if the request is unsuccessful or
- * has not yet been sent.
- */
- readonly attribute AString responseText;
-
-
- /**
- * The status of the response to the request for HTTP requests.
- */
- readonly attribute unsigned long status;
-
- /**
- * The string representing the status of the response for
- * HTTP requests.
- */
- readonly attribute AUTF8String statusText;
-
- /**
- * If the request has been sent already, this method will
- * abort the request.
- */
- void abort();
-
- /**
- * Returns all of the response headers as a string for HTTP
- * requests.
- *
- * Note that this will return all the headers from the *current*
- * part of a multipart request, not from the original channel.
- *
- * @returns A string containing all of the response headers.
- * NULL if the response has not yet been received.
- */
- string getAllResponseHeaders();
-
- /**
- * Returns the text of the header with the specified name for
- * HTTP requests.
- *
- * @param header The name of the header to retrieve
- * @returns A string containing the text of the header specified.
- * NULL if the response has not yet been received or the
- * header does not exist in the response.
- */
- ACString getResponseHeader(in AUTF8String header);
-
- /**
- * Native (non-script) method to initialize a request. Note that
- * the request is not sent until the <code>send</code> method
- * is invoked.
- *
- * Will abort currently active loads.
- *
- * After the initial response, all event listeners will be cleared.
- * Call open() before setting new event listeners.
- *
- * @param method The HTTP method, for example "POST" or "GET". Ignored
- * if the URL is not a HTTP(S) URL.
- * @param url The URL to which to send the request.
- * @param async Whether the request is synchronous or asynchronous
- * i.e. whether send returns only after the response
- * is received or if it returns immediately after
- * sending the request. In the latter case, notification
- * of completion is sent through the event listeners.
- * This argument must be true if the multipart
- * attribute has been set to true, or an exception will
- * be thrown.
- * @param user A username for authentication if necessary.
- * @param password A password for authentication if necessary.
- */
- [noscript] void openRequest(in AUTF8String method,
- in AUTF8String url,
- in boolean async,
- in AString user,
- in AString password);
-
- /**
- * Meant to be a script-only method for initializing a request.
- * The parameters are similar to the ones detailed in the
- * description of <code>openRequest</code>, but the last
- * 3 are optional.
- *
- * Will abort currently active loads.
- *
- * After the initial response, all event listeners will be cleared.
- * Call open() before setting new event listeners.
- *
- * @param method The HTTP method - either "POST" or "GET". Ignored
- * if the URL is not a HTTP URL.
- * @param url The URL to which to send the request.
- * @param async (optional) Whether the request is synchronous or
- * asynchronous i.e. whether send returns only after
- * the response is received or if it returns immediately after
- * sending the request. In the latter case, notification
- * of completion is sent through the event listeners.
- * The default value is true.
- * This argument must be true if the multipart
- * attribute has been set to true, or an exception will
- * be thrown.
- * @param user (optional) A username for authentication if necessary.
- * The default value is the empty string
- * @param password (optional) A password for authentication if necessary.
- * The default value is the empty string
- */
- void open(in AUTF8String method, in AUTF8String url);
-
- /**
- * Sends the request. If the request is asynchronous, returns
- * immediately after sending the request. If it is synchronous
- * returns only after the response has been received.
- *
- * After the initial response, all event listeners will be cleared.
- * Call open() before setting new event listeners.
- *
- * @param body Either an instance of nsIDOMDocument, nsIInputStream
- * or a string (nsISupportsString in the native calling
- * case). This is used to populate the body of the
- * HTTP request if the HTTP request method is "POST".
- * If the parameter is a nsIDOMDocument, it is serialized.
- * If the parameter is a nsIInputStream, then it must be
- * compatible with nsIUploadChannel.setUploadStream, and a
- * Content-Length header will be added to the HTTP request
- * with a value given by nsIInputStream.available. Any
- * headers included at the top of the stream will be
- * treated as part of the message body. The MIME type of
- * the stream should be specified by setting the Content-
- * Type header via the setRequestHeader method before
- * calling send.
- */
- void send(in nsIVariant body);
-
- /**
- * Sets a HTTP request header for HTTP requests. You must call open
- * before setting the request headers.
- *
- * @param header The name of the header to set in the request.
- * @param value The body of the header.
- */
- void setRequestHeader(in AUTF8String header, in AUTF8String value);
-
- /**
- * The state of the request.
- *
- * Possible values:
- * 0 UNINITIALIZED open() has not been called yet.
- * 1 LOADING send() has not been called yet.
- * 2 LOADED send() has been called, headers and status are available.
- * 3 INTERACTIVE Downloading, responseText holds the partial data.
- * 4 COMPLETED Finished with all operations.
- */
- readonly attribute long readyState;
-
- /**
- * Override the mime type returned by the server (if any). This may
- * be used, for example, to force a stream to be treated and parsed
- * as text/xml, even if the server does not report it as such. This
- * must be done before the <code>send</code> method is invoked.
- *
- * @param mimetype The type used to override that returned by the server
- * (if any).
- */
- void overrideMimeType(in AUTF8String mimetype);
-
- /**
- * Set to true if the response is expected to be a stream of
- * possibly multiple (XML) documents. If set to true, the content
- * type of the initial response must be multipart/x-mixed-replace or
- * an error will be triggerd. All requests must be asynchronous.
- *
- * This enables server push. For each XML document that's written to
- * this request, a new XML DOM document is created and the onload
- * handler is called inbetween documents. Note that when this is
- * set, the onload handler and other event handlers are not reset
- * after the first XML document is loaded, and the onload handler
- * will be called as each part of the response is received.
- */
- attribute boolean multipart;
- };
-
-
- [scriptable, function, uuid(6459B7CE-6B57-4934-A0AF-0133BA6F9085)]
- interface nsIOnReadyStateChangeHandler : nsISupports {
- /**
- * Helper to implement the onreadystatechange callback member.
- * You should not need to use this.
- */
- void handleEvent();
- };
-
- [scriptable, uuid(9deabc90-28d5-41d3-a660-474f2254f4ba)]
- interface nsIJSXMLHttpRequest : nsISupports {
- /**
- * Meant to be a script-only mechanism for setting a load event listener.
- * The attribute is expected to be JavaScript function object. When
- * the load event occurs, the function is invoked.
- * This attribute should not be used from native code!!
- *
- * After the initial response, all event listeners will be cleared.
- * Call open() before setting new event listeners.
- *
- * Mozilla only.
- */
- attribute nsIDOMEventListener onload;
-
- /**
- * Meant to be a script-only mechanism for setting an error event listener.
- * The attribute is expected to be JavaScript function object. When
- * the error event occurs, the function is invoked.
- * This attribute should not be used from native code!!
- *
- * After the initial response, all event listeners will be cleared.
- * Call open() before setting new event listeners.
- *
- * Mozilla only.
- */
- attribute nsIDOMEventListener onerror;
-
- /**
- * Meant to be a script-only mechanism for setting a progress event listener.
- * The attribute is expected to be JavaScript function object. When
- * the error event occurs, the function is invoked.
- * This attribute should not be used from native code!!
- * This event listener may be called multiple times during the open request.
- *
- * After the initial response, all event listeners will be cleared.
- * Call open() before setting new event listeners.
- *
- * Mozilla only.
- */
- attribute nsIDOMEventListener onprogress;
-
- /**
- * Meant to be a script-only mechanism for setting a callback function.
- * The attribute is expected to be JavaScript function object. When the
- * readyState changes, the callback function will be called.
- * This attribute should not be used from native code!!
- *
- * After the initial response, all event listeners will be cleared.
- * Call open() before setting new event listeners.
- */
- attribute nsIOnReadyStateChangeHandler onreadystatechange;
- };
-
- %{ C++
- #define NS_XMLHTTPREQUEST_CID \
- { /* d164e770-4157-11d4-9a42-000064657374 */ \
- 0xd164e770, 0x4157, 0x11d4, \
- {0x9a, 0x42, 0x00, 0x00, 0x64, 0x65, 0x73, 0x74} }
- #define NS_XMLHTTPREQUEST_CONTRACTID \
- "@mozilla.org/xmlextras/xmlhttprequest;1"
- %}
-